<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Data::Structure::Util - Change nature of data within a structure - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of Data-Structure-Util - MetaCPAN" href="https://metacpan.org/dist/Data-Structure-Util/releases.rss" />
        <link rel="canonical" href="./Data::Structure::Util.html" />
        <meta name="description" content="Change nature of data within a structure" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/Data::Structure::Util" />
<meta name="twitter:title"       content="Data::Structure::Util" />
<meta name="twitter:description" content="Change nature of data within a structure" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./Data::Structure::Util.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of Data-Structure-Util was released.">
      <span class="relatize">08 Mar 2015 10:35:04 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/Data-Structure-Util">Data-Structure-Util</a>
  </li>
  <li>
    Module version: 0.16
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/Data-Structure-Util/source/lib/Data/Structure/Util.pm">Source</a>
    (<a href="https://metacpan.org/dist/Data-Structure-Util/source/lib/Data/Structure/Util.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/Data-Structure-Util/source/lib/Data/Structure">Browse</a>
    (<a href="https://metacpan.org/dist/Data-Structure-Util/source/lib/Data/Structure?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/Data-Structure-Util/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/Data-Structure-Util/contribute">How to Contribute</a>
    </li>
    <li>
        <a rel="noopener nofollow" data-keyboard-shortcut="g r" href="https://github.com/AndyA/Data--Structure--Util">Repository</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Structure-Util">Issues</a>
      (3)
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=Data-Structure-Util+0.16" title="Matrix">Testers</a>
        <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/D/Data-Structure-Util.html?oncpan=1&amp;distmat=1&amp;version=0.16&amp;grade=2" style="color: #090">7799</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/D/Data-Structure-Util.html?oncpan=1&amp;distmat=1&amp;version=0.16&amp;grade=3" style="color: #900">1</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/D/Data-Structure-Util.html?oncpan=1&amp;distmat=1&amp;version=0.16&amp;grade=4">6</a>)</span>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/ANDYA/Data-Structure-Util-0.16">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on Data-Structure-Util who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 0
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/Data-Structure-Util-0.16/index.html">93.75% Coverage </a>
    </li>
    <li>
      License: perl_5
    </li>
    <li>
      Perl: v5.8.0
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/Data-Structure-Util/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/A/AN/ANDYA/Data-Structure-Util-0.16.tar.gz">
      Download (<span itemprop="fileSize">23.38KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FANDYA%2FData-Structure-Util-0.16%2Flib%2FData%2FStructure%2FUtil.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Data-Structure-Util/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Data-Structure-Util/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:Data-Structure-Util">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="Data-Structure-Util">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Data/Structure/Util.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="ANDYA/Data-Structure-Util-0.16"
>0.16
  (ANDYA on 2015-03-08)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.15"
>0.15
  (ANDYA on 2008-03-09)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.14"
>0.14
  (ANDYA on 2008-03-09)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.13"
>0.13
  (ANDYA on 2008-03-08)</option>
<option
  
  value="FOTANGO/Data-Structure-Util-0.12"
>0.12
  (FOTANGO on 2006-06-21)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.11"
>0.11
  (PDENIS on 2004-09-10)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.10"
>0.10
  (PDENIS on 2004-06-26)</option>
<optgroup label="BackPAN">'
<option
  
  value="PDENIS/Data-Structure-Util-0.09"
>0.09
  (PDENIS on 2004-03-26)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.08"
>0.08
  (PDENIS on 2004-01-20)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.07"
>0.07
  (PDENIS on 2004-01-19)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.06"
>0.06
  (PDENIS on 2003-12-30)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.05"
>0.05
  (PDENIS on 2003-11-11)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.04"
>0.04
  (PDENIS on 2003-11-06)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.03"
>0.03
  (PDENIS on 2003-11-05)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.02"
>0.02
  (PDENIS on 2003-11-04)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.01"
>0.01
  (PDENIS on 2003-11-04)</option>
</optgroup>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/ANDYA/Data-Structure-Util-0.16/diff/' + encodeURIComponent(this.value) + '/lib/Data/Structure/Util.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="ANDYA/Data-Structure-Util-0.16"
>0.16
  (ANDYA on 2015-03-08)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.15"
>0.15
  (ANDYA on 2008-03-09)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.14"
>0.14
  (ANDYA on 2008-03-09)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.13"
>0.13
  (ANDYA on 2008-03-08)</option>
<option
  
  value="FOTANGO/Data-Structure-Util-0.12"
>0.12
  (FOTANGO on 2006-06-21)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.11"
>0.11
  (PDENIS on 2004-09-10)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.10"
>0.10
  (PDENIS on 2004-06-26)</option>
<optgroup label="BackPAN">'
<option
  
  value="PDENIS/Data-Structure-Util-0.09"
>0.09
  (PDENIS on 2004-03-26)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.08"
>0.08
  (PDENIS on 2004-01-20)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.07"
>0.07
  (PDENIS on 2004-01-19)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.06"
>0.06
  (PDENIS on 2003-12-30)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.05"
>0.05
  (PDENIS on 2003-11-11)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.04"
>0.04
  (PDENIS on 2003-11-06)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.03"
>0.03
  (PDENIS on 2003-11-05)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.02"
>0.02
  (PDENIS on 2003-11-04)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.01"
>0.01
  (PDENIS on 2003-11-04)</option>
</optgroup>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><a href="https://metacpan.org/pod/Digest::MD5" title="Digest::MD5" class="ellipsis">Digest::MD5</a></li>
  <li><a href="https://metacpan.org/pod/Scalar::Util" title="Scalar::Util" class="ellipsis">Scalar::Util</a></li>
  <li><a href="https://metacpan.org/pod/Storable" title="Storable" class="ellipsis">Storable</a></li>
  <li><i class="ttip" title="dynamic_config enabled">and possibly others</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/Data::Structure::Util/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=Data%3A%3AStructure%3A%3AUtil">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=Data-Structure-Util">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/ANDYA/Data-Structure-Util-0.16/view/lib/Data/Structure/Util.pm">This version</a>
    </li>
    <li>
      <a href="./Data::Structure::Util.html">Latest version</a>
    </li>
    <li>
<div class="plussers">
<div class="nav-header">++ed by:</div>
<div>
<a class="display-all" href="https://metacpan.org/author/PAVELSR"><img src="https://www.gravatar.com/avatar/bdd3233525e2a6ca61bbc05752111c15?d=identicon&amp;s=20" title="PAVELSR" alt="PAVELSR"></a>
<a class="display-all" href="https://metacpan.org/author/PERLANCAR"><img src="https://www.gravatar.com/avatar/c66c9e215cc2342796cd87ca82d044a8?d=identicon&amp;s=20" title="PERLANCAR" alt="PERLANCAR"></a>
<a class="display-all" href="https://metacpan.org/author/XLAT"><img src="https://www.gravatar.com/avatar/a477fe9cd31dd7f08e1962deff6ef5c5?d=identicon&amp;s=20" title="XLAT" alt="XLAT"></a>
<a class="display-all" href="https://metacpan.org/author/DEMIAN"><img src="https://www.gravatar.com/avatar/4eead33e026cb118da76f3bc2e0e723f?d=identicon&amp;s=20" title="DEMIAN" alt="DEMIAN"></a>
<a class="display-all" href="https://metacpan.org/author/TINITA"><img src="https://www.gravatar.com/avatar/41d992bb7c01d13ffb8b7bf1ed355e91?d=identicon&amp;s=20" title="TINITA" alt="TINITA"></a>
</div>
<!-- Display counts of plussers-->
<div>
    <a href="https://metacpan.org/dist/Data-Structure-Util/plussers">5 PAUSE users</a>
</div>
<div>
    2 non-PAUSE users
</div>
</div>
    </li>
    <li>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/ANDYA" class="author-name">Andy Armstrong</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Data/Structure/Util.pm&#39;" class="">
<option
  selected
  value="ANDYA/Data-Structure-Util-0.16"
>0.16
  (ANDYA on 2015-03-08)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.15"
>0.15
  (ANDYA on 2008-03-09)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.14"
>0.14
  (ANDYA on 2008-03-09)</option>
<option
  
  value="ANDYA/Data-Structure-Util-0.13"
>0.13
  (ANDYA on 2008-03-08)</option>
<option
  
  value="FOTANGO/Data-Structure-Util-0.12"
>0.12
  (FOTANGO on 2006-06-21)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.11"
>0.11
  (PDENIS on 2004-09-10)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.10"
>0.10
  (PDENIS on 2004-06-26)</option>
<optgroup label="BackPAN">'
<option
  
  value="PDENIS/Data-Structure-Util-0.09"
>0.09
  (PDENIS on 2004-03-26)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.08"
>0.08
  (PDENIS on 2004-01-20)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.07"
>0.07
  (PDENIS on 2004-01-19)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.06"
>0.06
  (PDENIS on 2003-12-30)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.05"
>0.05
  (PDENIS on 2003-11-11)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.04"
>0.04
  (PDENIS on 2003-11-06)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.03"
>0.03
  (PDENIS on 2003-11-05)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.02"
>0.02
  (PDENIS on 2003-11-04)</option>
<option
  
  value="PDENIS/Data-Structure-Util-0.01"
>0.01
  (PDENIS on 2003-11-04)</option>
</optgroup>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/Data-Structure-Util">Data-Structure-Util-0.16</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage two &#10;
          • 29 direct dependents &#10;          • 96 total dependents
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="5"  y="0" width="4" height="15" fill="#7ea3f2" />
      <rect x="10"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="Data-Structure-Util-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="Data-Structure-Util-0.16">
    <input type="hidden" name="author" value="ANDYA">
    <input type="hidden" name="distribution" value="Data-Structure-Util">
    <button type="submit" class="favorite highlight"><span>7</span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./Data::Structure::Util.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite highlight">
<span>7</span> ++</a>
</div>
   / <span>Data::Structure::Util</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./Data::Structure::Util.html#NAME">NAME</a></li>
  <li><a href="./Data::Structure::Util.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./Data::Structure::Util.html#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="./Data::Structure::Util.html#FUNCTIONS">FUNCTIONS</a>
    <ul>
      <li><a href="./Data::Structure::Util.html#Manipulating-Data-Structures">Manipulating Data Structures</a></li>
      <li><a href="./Data::Structure::Util.html#Object-Blessing">Object Blessing</a></li>
      <li><a href="./Data::Structure::Util.html#utf8-Manipulation-Functions">utf8 Manipulation Functions</a></li>
    </ul>
  </li>
  <li><a href="./Data::Structure::Util.html#SEE-ALSO">SEE ALSO</a></li>
  <li><a href="./Data::Structure::Util.html#REPOSITORY">REPOSITORY</a></li>
  <li><a href="./Data::Structure::Util.html#BUGS">BUGS</a></li>
  <li><a href="./Data::Structure::Util.html#THANKS-TO">THANKS TO</a></li>
  <li><a href="./Data::Structure::Util.html#AUTHOR">AUTHOR</a></li>
  <li><a href="./Data::Structure::Util.html#COPYRIGHT">COPYRIGHT</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p>Data::Structure::Util - Change nature of data within a structure</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code>    use Data::Structure::Util qw(
      has_utf8 utf8_off utf8_on unbless get_blessed get_refs
      has_circular_ref circular_off signature
    );

    # get the objects in the data structure
    my $objects_arrayref = get_blessed( $data );

    # unbless all objects
    unbless( $data );

    if ( has_circular_ref( $data ) ) {
        print &quot;Removing circular ref!\n&quot;;
        circular_off( $data );
    }

    # convert back to latin1 if needed and possible
    utf8_off( $data ) if defined has_utf8( $data );</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p><code>Data::Structure::Util</code> is a toolbox to manipulate the data inside a data structure. It can process an entire tree and perform the operation requested on each appropriate element.</p>

<p>For example: It can transform all strings within a data structure to utf8 or transform any utf8 string back to the default encoding. It can remove the blessing on any reference. It can collect all the objects or detect if there is a circular reference.</p>

<p>It is written in C for decent speed.</p>

<h1 id="FUNCTIONS">FUNCTIONS</h1>

<p>All Data::Structure::Util functions operate on a whole tree. If you pass them a simple scalar then they will operate on that one scalar. However, if you pass them a reference to a hash, array, or scalar then they will iterate though that structure and apply the manipulation to all elements, and in turn if they are references to hashes, arrays or scalars to all their elements and so on, recursively.</p>

<p>For speed reasons all manipulations that alter the data structure do in- place manipulation meaning that rather than returning an altered copy of the data structure the passed data structure which has been altered.</p>

<h2 id="Manipulating-Data-Structures"><a id="Manipulating"></a>Manipulating Data Structures</h2>

<dl>

<dt id="has_circular_ref($ref)"><a id="has_circular_ref"></a><a id="has_circular_ref-ref"></a>has_circular_ref($ref)</dt>
<dd>

<p>This function detects if the passed data structure has a circular reference, that is to say if it is possible by following references contained in the structure to return to a part of the data structure you have already visited. Data structures that have circular references will not be automatically reclaimed by Perl&#39;s garbage collector.</p>

<p>If a circular reference is detected the function returns a reference to an element within circuit, otherwise the function will return a false value.</p>

<p>If the version of perl that you are using supports weak references then any weak references found within the data structure will not be traversed, meaning that circular references that have had links successfully weakened will not be returned by this function.</p>

</dd>
<dt id="circular_off($ref)"><a id="circular_off"></a><a id="circular_off-ref"></a>circular_off($ref)</dt>
<dd>

<p>Detects circular references in $ref (as above) and weakens a link in each so that they can be properly garbage collected when no external references to the data structure are left.</p>

<p>This means that one (or more) of the references in the data structure will be told that the should not count towards reference counting. You should be aware that if you later modify the data structure and leave parts of it only &#39;accessible&#39; via weakened references that those parts of the data structure will be immediately garbage collected as the weakened references will not be strong enough to maintain the connection on their own.</p>

<p>The number of references weakened is returned.</p>

</dd>
<dt id="get_refs($ref)"><a id="get_refs"></a><a id="get_refs-ref"></a>get_refs($ref)</dt>
<dd>

<p>Examine the data structure and return a reference to flat array that contains one copy of every reference in the data structure you passed.</p>

<p>For example:</p>

<pre><code>    my $foo = {
        first  =&gt; [ &quot;inner&quot;, &quot;array&quot;, { inmost =&gt; &quot;hash&quot; } ],
        second =&gt; \&quot;refed scalar&quot;,
    };

    use Data::Dumper;
    # tell Data::Dumper to show nodes multiple times
    $Data::Dumper::Deepcopy = 1;
    print Dumper get_refs( $foo );

    $VAR1 = [
        { &#39;inmost&#39; =&gt; &#39;hash&#39; },
        [ &#39;inner&#39;, &#39;array&#39;, { &#39;inmost&#39; =&gt; &#39;hash&#39; } ],
        \&#39;refed scalar&#39;,
        {
            &#39;first&#39;  =&gt; [ &#39;inner&#39;, { &#39;inmost&#39; =&gt; &#39;hash&#39; }, &#39;array&#39; ],
            &#39;second&#39; =&gt; \&#39;refed scalar&#39;
        }
    ];</code></pre>

<p>As you can see, the data structure is traversed depth first, so the top most references should be the last elements of the array. See <a href="https://metacpan.org/pod/get_blessed($ref)">get_blessed($ref)</a> below for a similar function for blessed objects.</p>

</dd>
<dt id="signature($ref)"><a id="signature"></a><a id="signature-ref"></a>signature($ref)</dt>
<dd>

<p>Returns a md5 of the passed data structure. Any change at all to the data structure will cause a different md5 to be returned.</p>

<p>The function examines the structure, addresses, value types and flags to generate the signature, meaning that even data structures that would look identical when dumped with Data::Dumper produce different signatures:</p>

<pre><code>    $ref1 = { key1 =&gt; [] };

    $ref2 = $ref1;
    $ref2-&gt;{key1} = [];

    # this produces the same result, as they look the same
    # even though they are different data structures
    use Data::Dumper;
    use Digest::MD5 qw(md5_hex);
    print md5_hex( Dumper( $ref1 ) ), &quot; &quot;, md5_hex( Dumper( $ref2 ) ), &quot;\n&quot;;
    # cb55d41da284a5869a0401bb65ab74c1 cb55d41da284a5869a0401bb65ab74c1

    # this produces differing results
    use Data::Structure::Util qw(signature);
    print signature( $ref1 ), &quot; &quot;, signature( $ref2 ), &quot;\n&quot;;
    # 5d20c5e81a53b2be90521167aefed9db 8b4cba2cbae0fec4bab263e9866d3911</code></pre>

</dd>
</dl>

<h2 id="Object-Blessing"><a id="Object"></a>Object Blessing</h2>

<dl>

<dt id="unbless($ref)"><a id="unbless"></a><a id="unbless-ref"></a>unbless($ref)</dt>
<dd>

<p>Remove the blessing from any objects found within the passed data structure. For example:</p>

<pre><code>    my $foo = {
        &#39;a&#39; =&gt; bless( { &#39;b&#39; =&gt; bless( {}, &quot;c&quot; ), }, &quot;d&quot; ),
        &#39;e&#39; =&gt; [ bless( [], &quot;f&quot; ), bless( [], &quot;g&quot; ), ]
    };

    use Data::Dumper;
    use Data::Structure::Util qw(unbless);
    print Dumper( unbless( $foo ) );

    $VAR1 = {
        &#39;a&#39; =&gt; { &#39;b&#39; =&gt; {} },
        &#39;e&#39; =&gt; [ [], [] ]
    };</code></pre>

<p>Note that the structure looks inside blessed objects for other objects to unbless.</p>

</dd>
<dt id="get_blessed($ref)"><a id="get_blessed"></a><a id="get_blessed-ref"></a>get_blessed($ref)</dt>
<dd>

<p>Examine the data structure and return a reference to flat array that contains every object in the data structure you passed. For example:</p>

<pre><code>    my $foo = {
        &#39;a&#39; =&gt; bless( { &#39;b&#39; =&gt; bless( {}, &quot;c&quot; ), }, &quot;d&quot; ),
        &#39;e&#39; =&gt; [ bless( [], &quot;f&quot; ), bless( [], &quot;g&quot; ), ]
    };

    use Data::Dumper;
    # tell Data::Dumper to show nodes multiple times
    $Data::Dumper::Deepcopy = 1;
    use Data::Structure::Util qw(get_blessed);
    print Dumper( get_blessed( $foo ) );

    $VAR1 = [
        bless( {}, &#39;c&#39; ),
        bless( { &#39;b&#39; =&gt; bless( {}, &#39;c&#39; ) }, &#39;d&#39; ),
        bless( [], &#39;f&#39; ),
        bless( [], &#39;g&#39; )
    ];</code></pre>

<p>This function is essentially the same as <code>get_refs</code> but only returns blessed objects rather than all objects. As with that function the data structure is traversed depth first, so the top most objects should be the last elements of the array. Note also (as shown in the above example shows) that objects within objects are returned.</p>

</dd>
</dl>

<h2 id="utf8-Manipulation-Functions"><a id="utf8"></a>utf8 Manipulation Functions</h2>

<p>These functions allow you to manipulate the state of the utf8 flags in the scalars contained in the data structure. Information on the utf8 flag and it&#39;s significance can be found in <a href="https://metacpan.org/pod/Encode">Encode</a>.</p>

<dl>

<dt id="has_utf8($var)"><a id="has_utf8"></a><a id="has_utf8-var"></a>has_utf8($var)</dt>
<dd>

<p>Returns <code>$var</code> if the utf8 flag is enabled for <code>$var</code> or any scalar that a data structure passed in <code>$var</code> contains.</p>

<pre><code>    print &quot;this will be printed&quot;  if defined has_utf8( &quot;\x{1234}&quot; );
    print &quot;this won&#39;t be printed&quot; if defined has_utf8( &quot;foo bar&quot; );</code></pre>

<p>Note that you should not check the truth of the return value of this function when calling it with a single scalar as it is possible to have a string &quot;0&quot; or &quot;&quot; for which the utf8 flag set; Since <code>undef</code> can never have the utf8 flag set the function will never return a defined value if the data structure does not contain a utf8 flagged scalar.</p>

</dd>
<dt id="_utf8_off($var)"><a id="_utf8_off"></a><a id="utf8_off-var"></a>_utf8_off($var)</dt>
<dd>

<p>Recursively disables the utf8 flag on all scalars within $var. This is the same the <code>_utf8_off</code> function of <a href="https://metacpan.org/pod/Encode">Encode</a> but applies to any string within <code>$var</code>. The data structure is converted in-place, and as a convenience the passed variable is returned from the function.</p>

<p>This function makes no attempt to do any character set conversion to the strings stored in any of the scalars in the passed data structure. This means that if perl was internally storing any character as sequence of bytes in the utf8 encoding each byte in that sequence will then be henceforth treated as a character in it&#39;s own right.</p>

<p>For example:</p>

<pre><code>    my $emoticons = { smile =&gt; &quot;\x{236a}&quot; };
    use Data::Structure::Util qw(_utf8_on);
    print length( $emoticons-&gt;{smile} ), &quot;\n&quot;;    # prints 1
    _utf8_off( $emoticons );
    print length( $emoticons-&gt;{smile} ), &quot;\n&quot;;    # prints 3</code></pre>

</dd>
<dt id="_utf8_on($var)"><a id="_utf8_on"></a><a id="utf8_on-var"></a>_utf8_on($var)</dt>
<dd>

<p>Recursively enables the utf8 flag on all scalars within $var. This is the same the <code>_utf8_on</code> function of <a href="https://metacpan.org/pod/Encode">Encode</a> but applies to any string within <code>$var</code>. The data structure is converted in-place and as a convenience the passed variable is returned from the function.</p>

<p>As above, this makes no attempt to do any character set conversion meaning that unless your string contains the valid utf8 byte sequences for the characters you want you are in trouble. <b>In some cases incorrect byte sequences can segfault perl</b>. In particular, the regular expression engine has significant problems with invalid utf8 that has been incorrectly marked as utf8. You should know what you are doing if you are using this function; Consider using the Encode module as an alternative.</p>

<p>Contrary example to the above:</p>

<pre><code>    my $emoticons = { smile =&gt; &quot;\342\230\272&quot; };
    use Data::Structure::Util qw(_utf8_on);
    print length( $emoticons-&gt;{smile} ), &quot;\n&quot;;    # prints 3
    _utf8_on( $emoticons );
    print length( $emoticons-&gt;{smile} ), &quot;\n&quot;;    # prints 1</code></pre>

</dd>
<dt id="utf8_on($var)"><a id="utf8_on"></a><a id="utf8_on-var1"></a>utf8_on($var)</dt>
<dd>

<p>This routine performs a <code>sv_utf8_upgrade</code> on each scalar string in the passed data structure that does not have the utf8 flag turned on. This will cause the perl to change the method it uses internally to store the string from the native encoding (normally Latin-1 unless locales come into effect) into a utf8 encoding and set the utf8 flag for that scalar. This means that single byte letters will now be represented by multi-byte sequences. However, as long as the <code>use bytes</code> pragma is not in effect the string will be the same length as because as far as perl is concerned the string still contains the same number of characters (but not bytes).</p>

<p>This routine is significantly different from <code>_utf8_on</code>; That routine assumes that your string is encoded in utf8 but was marked (wrongly) in the native encoding. This routine assumes that your string is encoded in the native encoding and is marked that way, but you&#39;d rather it be encoded and marked as utf8.</p>

</dd>
<dt id="utf8_off($var)"><a id="utf8_off"></a><a id="utf8_off-var1"></a>utf8_off($var)</dt>
<dd>

<p>This routine performs a <code>sv_utf8_downgrade</code> on each scalar string in the passed data structure that has the utf8 flag turned on. This will cause the perl to change the method it uses internally to store the string from the utf8 encoding into a the native encoding (normally Latin-1 unless locales are used) and disable the utf8 flag for that scalar. This means that multiple byte sequences that represent a single character will be replaced by one byte per character. However, as long as the <code>use bytes</code> pragma is not in effect the string will be the same length as because as far as perl is concerned the string still contains the same number of characters (but not bytes).</p>

<p>Please note that not all strings can be converted from utf8 to the native encoding; In the case that the utf8 character has no corresponding character in the native encoding Perl will die with &quot;Wide character in subroutine entry&quot; exception.</p>

<p>This routine is significantly different from <code>_utf8_off</code>; That routine assumes that your string is encoded in utf8 and that you want to simply mark it as being in the native encoding so that perl will treat every byte that makes up the character sequences as a character in it&#39;s own right in the native encoding. This routine assumes that your string is encoded in utf8, but you want it each character that is currently represented by multi-byte strings to be replaced by the single byte representation of the same character.</p>

</dd>
</dl>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<p><a href="https://metacpan.org/pod/Encode">Encode</a>, <a href="https://metacpan.org/pod/Scalar::Util">Scalar::Util</a>, <a href="https://metacpan.org/pod/Devel::Leak">Devel::Leak</a>, <a href="https://metacpan.org/pod/Devel::LeakTrace">Devel::LeakTrace</a></p>

<p>See the excellent article http://www.perl.com/pub/a/2002/08/07/proxyobject.html from Matt Sergeant for more info on circular references.</p>

<h1 id="REPOSITORY">REPOSITORY</h1>

<p>https://github.com/AndyA/Data--Structure--Util</p>

<h1 id="BUGS">BUGS</h1>

<p><code>signature()</code> is sensitive to the hash randomisation algorithm</p>

<p>This module only recurses through basic hashes, lists and scalar references. It doesn&#39;t attempt anything more complicated.</p>

<h1 id="THANKS-TO"><a id="THANKS"></a>THANKS TO</h1>

<p>James Duncan and Arthur Bergman who helped me and found a name for this module. Leon Brocard and Richard Clamp have provided invaluable help to debug this module. Mark Fowler rewrote large chunks of the documentation and patched a few bugs.</p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>This release by Andy Armstrong &lt;andy@hexten.net&gt;</p>

<p>Originally by Pierre Denis &lt;pdenis@fotango.com&gt;</p>

<p>http://opensource.fotango.com/</p>

<h1 id="COPYRIGHT">COPYRIGHT</h1>

<p>Copyright 2003, 2004 Fotango - All Rights Reserved.</p>

<p>This module is released under the same license as Perl itself.</p></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install Data::Structure::Util, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm Data::Structure::Util</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install Data::Structure::Util</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./Data::Structure::Util.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
